<HTML>
<CENTER><A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A> 
</CENTER>






<H3>lpp tool 
</H3>
<P><B>Purpose:</B>
</P>
<P>This is lpp (liggghts post processing), an update to pizza.py offering better visualization
of granular (DEM) LIGGGHTS or LAMMPS simulations using pizza.py via VTK files
</P>
<HR>

<P><B>Description:</B>
</P>
<P>This update provides the possibilty to convert LIGGGHTS/LAMMPS dump files to VTK exporting:
</P>
<LI>particle radius, 

<LI>particle velocity and rotational velocity vector, 

<LI>particle force and torque vector, 

<LI>customized vectors (e.g. calculated by a fix, compute or variable) 

<LI>customized scalars (e.g. calculated by a fix, compute or variable) 

<P>where the names are automatically assigned.
</P>
<P>The lpp tool runs in parallel (shared-memory) using the python "multiprocessing" tool. The number of processors can be controlled via command line args (see below).
</P>
<P>Additionally, the simulation box is also exported into VTK format
and stored in an "*_boundingBox.vtk" file
</P>
<HR>

<P><B>Prerequisites for Usage:</B>
</P>
<P>To be able to use the lpp tool, please use a dump custom command like the
following in your LIGGGHTS/LAMMPS input script:
</P>
<PRE>dump d0 all custom 100 dump*.example id type x y z ix iy iz vx vy vz fx fy fz 
omegax omegay omegaz radius (customScalars) (customVectors) 
</PRE>
<P>It is mandatory to use "x y z" in the dump custom command. The dump file
generated by LIGGGHTS/LAMMPS will look like this:
</P>
<PRE>ITEM: TIMESTEP
5000
ITEM: NUMBER OF ATOMS
2988
ITEM: BOX BOUNDS
-0.05 0.05
-0.05 0.05
0 0.6
ITEM: ATOMS id type x y z vx vy vz fx fy fz omegax omegay omegaz radius 
</PRE>
<P>The last line contains the name strings for the per-atom quanitites.
If the syntax of a name string triple of names meets one of the following 
specifications this triple is recognized as a vector:
</P>
<LI>f_vectorname[i] f_vectorname[i+1] f_vectorname[i+2] 

<LI>c_vectorname[i] c_vectorname[i+1] c_vectorname[i+2] 

<LI>v_vectorname[i] v_vectorname[i+1] v_vectorname[i+2] 

<LI>vectornamex vectornamey vectornamez 

<P>"vectorname" can be any name (e.g. "v" for velocity, "tq" for torque,
etc., a fix or compute id, or a per-atom variable name.)
</P>
<P>All other quantities are recognized as scalars.
</P>
<HR>

<P><B>Usage:</B>
</P>
<P>After the simulation is finished, type "lpp dump.mySimulation" where "dump.mySimulation" 
has to be replaced the name of your dump file  or type "lpp dump*.mySimulation"
</P>
<P>For more command line options, see below.
</P>
<P>Now open paraview (www.paraview.org) and import the VTK files. To display the
particles correctly, you should  first create a glyph by clicking on the "glyph" 
button and then in the object inspector:
</P>
<LI>Choose Scalars -->"radius" 

<LI>Glyph type -->"Sphere" 

<LI>Radius -->"1" 

<LI>Scale mode -->"Scalar" 

<LI>Set Scale Factor -->"1" 

<P>In a similar fashion, you can set up vector glyphs to visualize velocity etc.
</P>
<HR>

<P><B>Command Line Options:</B>
</P>
<P>A few command line options are avaliable to control lpp:
</P>
<P><B>-o fname</B>       : define output file names (default is liggghts + timestep number). This option can also be used to write to a specified folder, eg. "lpp -o foo/bar dump*" will create files bar1000.vtk, bar2000.vtk etc. in the directory ./foo while "lpp -o foo/ dump*" will create files named liggghts1000.vtk, ligggghts2000.vtk etc. in ./foo (providing the directory exists, lpp will not create any directories for you!)
</P>
<P><B>--chunksize</B>    : sets the amount of dumpfiles processed per chunk, the default is 8. Increasing the chunksize can improve performance, but the chunksize is limited by the amount of RAM on your system. Also keep in mind that multiple chunks may be processed depending on your --cpunum settings, and thus RAM demand is multiplied.
</P>
<P><B>--cpunum</B>       : sets the number of processes to start, default (and maximum) is the amount of cpu cores avaliable at your system.
</P>
<P><B>--debug</B>        : prints debug information, usually not needed
</P>
<P><B>--help</B>         : writes a help message and exits
</P>
<P><B>--no-overwrite</B> : if set lpp does not process dump-files that have already been
converted, i.e. where the vtk-file already exists.
</P>
<P><B>--quiet</B>        : suppresses all output but error messages (also discards --debug)
</P>
<HR>

<P><B>Related tools:</B>
</P>
<P><A HREF = "vtk.html">vtk</A>, <A HREF = "dump.html">dump</A>,
</P>
<HR>

<P><B>Prerequisites:</B> 
</P>
<P>Python <A HREF = "http://docs.python.org/library/multiprocessing.html">multiprocessing library</A> (new in python 2.6)
</P>
</HTML>
